Enforce CPU+memory limits on Actor containers and stream systemInfo events to runs - #28

Review fixes on the resource-limits/events-channel work:

- Every accepted events websocket now has an error listener, and the upgrade
  handler contains connection-setup failures to that one socket - previously a
  single malformed frame from any container crashed the whole runtime process.
- Graceful shutdown terminates the events server's own clients before closing
  the HTTP server: closeAllConnections() never destroys upgraded sockets, so
  shutdown hung whenever an Actor was connected. The comments claiming
  otherwise are corrected and shutdown.test.ts now guards this for the events
  socket like it already did for log streams.
- docker-driver's startRun try/finally now also covers container.start(), the
  sampler creation, and container.logs(), so a throw in that window still
  stops the sampler and removes the container.
- abortRun derives its was-running decision inside the status transition's
  per-id mutex (new onBeforeTransition hook on transitionJobStatus) instead of
  a separate unguarded read that raced READY->RUNNING; the redundant registry
  read on the default abort path is gone.
- gracefully=true is now exercised over a real HTTP round trip in the
  integration suite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…s.ts

- Comments that cited ephemeral design/review documents now cite the durable
  requirements docs (requirements/actor-driver.md, requirements/api.md) or
  carry the rationale inline - most importantly the events websocket's
  no-authentication note, which now points at requirements/api.md instead of
  an artifact that never ships with the repo.
- The shutdown-ordering rationale (why the events server must terminate its
  own clients before closeServer) now lives only in
  EventsWebSocketServer.close()'s doc comment; the other three sites defer to
  it in one line.
- events-channel exports follow logs.ts's domain-prefixed convention:
  subscribeEvents / markEventsTerminal; the import alias in runs.ts is gone.

No behavior change: comments, import lines, test titles, and renamed
identifiers only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…ately

A repeat abort call while a gracefully-aborted run is still inside its
30-second window used to stop the container immediately, silently defeating
the window: the ABORTING status alone cannot distinguish "my transition just
landed" from "another caller's window is active". abortRun now captures that
distinction atomically (the pre-transition status reported inside the
status-transition mutex): a second gracefully=true call joins the active
window and returns the current record without re-triggering anything, while a
plain abort deliberately escalates to an immediate stop - the same behavior a
plain double-abort always had. The first caller's eventual finalization stays
a safe no-op under the existing terminal-status guard.

Also covers the over-capacity warning's memory-only and CPU-only arms with
dedicated unit tests and fixes a stale subscribe() comment reference.
requirements/api.md documents the join/escalate contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

Comment-only cleanup: constraints formerly cited as bare criterion or
iteration numbers now state the guarantee inline or cite the matching
requirements/*.md section (graceful-abort join/escalate contract, the
501-vs-404 spec-table rule, the APIFY_PROXY_PASSWORD contract, the
flusher-gated log-stream race). No code, identifiers, assertions, or
behavior changed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…omments

Comment-only: the two test comments that still cited a bare criterion number
now cite requirements/api.md's Graceful abort section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…dedupe

Final-review fixes on the resource-limits/events work:

- sampler.stop() bounds its wait for an in-flight stats() call with
  SAMPLER_STOP_GRACE_MS (mirroring LOG_DRAIN_GRACE_MS) - an unresponsive
  daemon could previously stall run finalization forever, leaving the record
  RUNNING with its timeout timer already cleared.
- memCurrentBytes now excludes the page cache the way docker stats does
  (usage minus inactive file bytes, cgroup v1/v2 aware), so autoscaling sees
  reclaimable memory as free instead of steadily inflating usage.
- The events websocket path regex rejects a trailing slash, matching the
  documented route exactly.
- The memory/CPU ratio helpers move from services/ to src/resources.ts so the
  driver no longer imports the services layer.
- Shared pollUntilTerminal helper replaces the near-duplicate poll loops in
  the log and events endpoints; the Docker stats test stub moves to
  test/unit/helpers/docker-stubs.ts.
- requirements/api.md's abort entry names the actually-mounted route; test
  titles describe behavior; previously untested branches (unmatched upgrade
  path, warning arms, poll edges) gain coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…frames

A Docker stats body missing memory_stats.usage produced a seven-field
systemInfo frame (dropped by the Python SDK's validation) and then poisoned
the memAvgBytes running average with NaN for the rest of the run; a body
missing cpu_stats threw synchronously into an unhandled rejection. The
sampler now checks both readings for presence and finiteness and skips the
whole tick when either is unusable - no frame, accumulators and the CPU delta
baseline untouched - so one bad sample costs one tick, never the run's
telemetry.

Also: the graceful-abort integration suites move byte-identical from
job-lifecycle.test.ts (1168 -> 802 lines) into graceful-abort.test.ts, the
sampler-grace paragraph in requirements/actor-driver.md now states the
bounded-wait semantics the code actually implements, and a test comment
states its constraint directly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

Two unit tests now reach the CPU snapshot guard's second clause (valid
total_usage, missing or non-finite system_cpu_usage - the cgroup v2 rootless
shape), asserting the tick is skipped and the next good sample recovers.
Three comments corrected: two now state their constraint directly, one
cross-file reference follows the graceful-abort suite to its new home, and
the split rationale no longer cites a policy the repo does not have.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

… test comments

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…ullet

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

…tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

Resolves four conflicts from the pnpm migration (#26) and the
Dockerfile-location work (#27):

- package-lock.json: accepted its deletion; ws and @types/ws are now
  carried by pnpm-lock.yaml, regenerated with pnpm install.
- package.json: kept both sides' dependency additions (json5, ws).
- docker-driver.ts and test-server.ts: kept both sides' imports; the
  driver-stub type import now names BuildContext and RunResourceSample.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

`sample_actor_resources_ts` and `sample_actor_resources_py` print the
memory and CPU the runtime granted the run, then one line per systemInfo
event, so the whole path this branch adds - cgroup limits, the sampler,
the events websocket and the injected env vars - is observable from a
single `apify call`.

The two differ in where the grant comes from, which is a property of the
SDKs rather than a choice: the JS SDK re-emits each frame verbatim, so a
JS Actor can read `memMaxBytes` off the event, while the Python SDK maps
the frame onto a usage-only structure with no total, so the Python sample
reads `Actor.configuration.memory_mbytes` instead.

Neither sample makes outbound requests, so unlike the crawling samples
they run offline once their base image is pulled.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp

The comments this branch added were roughly 40% of its own new lines,
against 24-33% in the same files at base; they now keep the constraints
that would otherwise be easy to reintroduce (the ws error listener, the
close-before-shutdown ordering, the sampler's bounded stop) and drop the
retelling around them.

The requirements grew by 187 lines describing how and why - moby's
validation rules, docker-modem's timeout handling, pydantic's field
requirements. They describe what the runtime does instead, in 87.

The standalone resource-reporting sample Actors are gone; the existing
samples log their granted resources and each systemInfo event, which is
the same demonstration without a second pair of Actors to maintain.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeN7rnNX67yNdUWsRMA7Sp